Skip to main content

Local Development with the SAML Toolkit

Overview​

The SAML Toolkit provides a local development environment to build and test SAML Single Sign-On (SSO) integrations. This toolkit simulates a SAML Identity Provider, allowing you to develop and validate your SAML client implementation before connecting to production environments.

To setup the SAML Toolkit, refer to the instructions in the README file.

Features​

  • Mock SAML Identity Provider - Full SAML 2.0 authentication flow
  • SAML Assertion Generation - XML assertions with non-editable mock attributes
  • Digital Signing - RS256-signed assertions using Candescent's private key
  • Assertion Encryption - Support for vendor-provided encryption certificates
  • E2E Validation - Automated tests to verify your integration
  • Downloadable Artifacts - Public key for signature verification

How It Works​

Configuration Page​

When the toolkit loads, it displays:

  • ACS URL input field
    • Enter your Test Assertion Consumer Service URL
  • Test encryption public certificate field
    • Enter the Test public certificate in PEM format
  • User attributes (first name, last name, member ID, and email)
    • non-editable mock data
  • Download Candescent Public Key
    • For signature verification

SAML Flow​

  1. Enter the test ACS URL and encryption public certificate

    • Test ACS URL Example:
      • If running locally: http://localhost:7080/api/saml-validator/acs
      • If running in Docker: http://host.docker.internal:7080/api/saml-validator/acs
    • Public Certificate: Enter the test public certificate in PEM format

  2. Click Run Simulation to generate and post the SAML assertion

  3. Backend processes the request:

    • Creates a SAML assertion in XML format.
    • Signs it using Candescent's private key.
    • Encrypts it using the test public key.
    • Base64-encodes the SAML response.
    • Posts it to the test ACS URL.

  4. The system displays:

    • A success screen upon receiving a successful response from the ACS endpoint.
    • An error screen with an appropriate error message when the ACS endpoint returns a failure response.

SAML Endpoints​

The toolkit exposes standard SAML endpoints:

EndpointMethodDescription
/api/saml/loginPOSTGenerates and posts SAML assertion to ACS URL
/api/saml/saml-settingGETRetrieves cached SAML settings
/api/public-keyGETReturns Candescent's public key for signature verification
/api/e2e-testPOSTRuns E2E tests and returns test reports as ZIP
/api/publish-configGETDownloads SAML configuration file
/api/healthGETHealth check

Validation​

Running the Validator​

  1. Navigate to http://localhost:8000/samlValidator.
  2. Click Run Validator to execute E2E tests.
  3. Review the validation report.
  4. Download reports (if needed).
  5. Publish SAML settings after successful validation.

The validator tests:

  • SAML assertion generation
  • Digital signing
  • Assertion encryption
  • ACS endpoint communication
  • Response validation

Validation Reports​

After running the validator, download:

  • e2e-report.html - Human-readable test report
  • jest-e2e.xml - XML test report with test cases.

Configuration​

Port Configuration​

Edit sample-web-app/config.json:

{
  "frontendPort": 8000,
  "backendPort": 9000
}

Values can be changed to any available ports on your system.

Component Overview​

ComponentTechnologyPurpose
FrontendReact, Redux ToolkitConfiguration UI and flow initiator
BackendNestJSMock SAML Identity Provider
client-web-appNestJSMock vendor environment for testing

About the client-web-app​

The client-web-app is a separate NestJS-based service that acts as a mock vendor environment for testing SAML SSO flows. It includes dummy ACS URL and test encryption public certificate to test the end-to-end flow.

Troubleshooting​

IssueCauseSolution
Port already in useAnother service runningEdit config.json to change ports
Backend won't startMissing private keyDefault keys should be in certs/. If missing, check certificate files
Frontend not connecting to backendBackend not runningEnsure backend is started on the configured port
Token validation failsCertificate mismatchRe-download public key from the toolkit
Docker pull: "unauthorized"Package visibilityThe package must be public. Verify at https://github.com/orgs/candescent-dev/packages
Docker pull: "no matching manifest for linux/arm64"Image built for AMD64 onlyUse --platform linux/amd64 flag or build locally (see Docker Setup)

Security Notice​

Default Development Certificates​

This toolkit includes pre-generated RSA keys in sample-web-app/backend/certs/ for convenience:

  • ✅ Safe for local development and testing.
  • ❌ NOT secure for production use.
  • ❌ NOT secure for QA/staging environments.

For Production Use​

If deploying to production or QA, generate your own keys using appropriate security practices.

Next Steps​

After validating your integration locally:

  1. Contact your PM - Request QA environment access.
  2. Complete the Setup Checklist - Provide application details.
  3. Begin QA testing - Validate with real Candescent endpoints.
  4. Proceed to certification - Complete FI environment testing.

References​